home *** CD-ROM | disk | FTP | other *** search
/ Collection of Tools & Utilities / Collection of Tools and Utilities.iso / edit / me_cd25.zip / DOC.ZIP / MUTT2.DOC < prev    next >
Text File  |  1992-11-09  |  38KB  |  923 lines
  1. ========================================================================
  2. ==     The Mutt2 Programming Language         Craig Durland 9/89 10/91 ==
  3. ========================================================================
  4.  
  5. Here is the documentation for the core Mutt2 programming language.
  6. There are probably many extensions, depending on what application Mutt
  7. is embedded in.  See the documentation for the application for more info.
  8.  
  9.  
  10.              Copyright 1991 Craig Durland
  11.     Distributed under the terms of the GNU General Public License.
  12.   Distributed "as is", without warranties of any kind, but comments,
  13.            suggestions and bug reports are welcome.
  14.  
  15. ======================================================================
  16. ==            Syntax                        ==
  17. ======================================================================
  18.  
  19. symbol    action
  20.   (    evaluate expression
  21.   )    end expression
  22.   {    start block
  23.   }    end block
  24.  
  25. SYNTAX
  26.   pgm   : {exp [exp ...]}, {}
  27.   exp   : (fcn [args]), (var [args]), var, const, ()
  28.   const : number (123, 0xAbC), string ("abc", 'abc'), TRUE, FALSE
  29.   arg   : block
  30.   block : pgm, exp or const
  31.   fcn   : a Mutt function (such as + or while) or defined function.
  32.  
  33. ======================================================================
  34. ==            Data Types                    ==
  35. ======================================================================
  36.  
  37. Mutt is a typed language.
  38.  
  39.   Type        id    What it is
  40.   ----        --    ---- --    --
  41.   BOOLEAN    0x05    TRUE or FALSE.
  42.   BLOB        0x06    A pointer to a block of data.
  43.   NUMBER    0x03    32 bit signed integer.
  44.   STRING    0x08    A bunch of characters.
  45.   LIST        0x09    A list of things.
  46.   VOID        0x01    A type of nothing.
  47.   FCNPTR    0x07    A pointer to a function.
  48.   CHARACTER    0x0A    This is not a real data type.  It is a helper
  49.             type.
  50.   REAL        0x04    Not implemented.
  51.  
  52. Id is a numeric constant that is used to identify a data type.  They are
  53.   used in Mutt programs when you need to talk about types (see
  54.   convert-to).
  55.  
  56. List Syntax
  57.   Sometimes I'll need to refer to the contents of a list.  To do that,
  58.     I'll use [<first element> <next element> ...].  Everything in "[]"
  59.     are the contents of the list.  "[]" by itself means the empty list.
  60.  
  61. ======================================================================
  62. ==                Return Values                ==
  63. ======================================================================
  64.  
  65. All blocks "return" a value.  Pgms return the value of the last exp
  66.   executed.  Note that a pgm can return values of different types.
  67. The class of a return value can be one of:
  68.   BOOLEAN, BLOB, NUMBER, STRING, LIST, VOID, FCNPTR.
  69.  
  70. ======================================================================
  71. ==             Variables (aka vars)                ==
  72. ======================================================================
  73. CREATION
  74.   Vars must be created before they can be used.
  75.   Global vars are initialized to:
  76.       bool            : FALSE
  77.       int, small-int, byte    : 0
  78.       string            : ""
  79.       list            : empty
  80.   Most Local vars are NOT initialized (ie they contain garbage when
  81.     created).  Local strings and lists are initialized the same as
  82.     globals.
  83. EVALUATION & ASSIGNMENT
  84.   Vars behave like fcns, ie (var) evaluates the var (returns its value)
  85.     and (var val) passes val to the var for assignment.  (var val)
  86.     returns val.  If you just want to evaluate a var, you can treat it
  87.     like a const - ie "var" is equivalent to "(var)".  Note, however,
  88.     doing this may cause logic bugs if var also happens to be the name
  89.     of a const (since the const is locked out).  See GOTCHAS.  In some
  90.     cases, (var) and var don't mean the same thing - see pointer.
  91.   Cascading assignment:  you can assign multiple vars the same value.
  92.     eg (int x y z)(x (y (z 123))) assigns 123 to x, y and z.
  93.     eg (int x)(string s 20)(x (convert-to NUMBER (s "123"))) sets s to
  94.       "123" and x to 123.
  95. SCOPE
  96.   The scope of a variable is the same as the pgm it is created in.
  97.   A variable created outside of a fcn (defun) is global - ie anybody
  98.     can get at it.  Global variables are local to the file (and any
  99.     included file(s)) they are created in.
  100.   For example:
  101.     If foo.mut contains:
  102.       (int foo)        ; declare and create global var "foo"
  103.       (defun "hoho" { (int bar) (bar foo) })
  104.       (foo 123)        ; assign 123 to foo
  105.     (load "foo.mut") will create a global var foo.  (hoho)
  106.     creates bar and sets it to 123.  hoho is done and bar is freed.
  107.     foo is still alive and equal to 123.
  108.  
  109. ======================================================================
  110. ==            Functions and Keywords                ==
  111. ======================================================================
  112. Everything in this list is a function (except those that have a return
  113.   class of zip).
  114.  
  115. A TOKEN is a bunch of letters, eg foo.
  116.  
  117. (KEYWORD args)        [arg class(s) : return class]
  118. -------- -----        ---- -------- -    ------ ------
  119.  
  120. ; (semi-colon)    A comment that extends to the end of the line
  121.  
  122. (== value value ...)          [STRINGs, NUMBERs or BOOLEANs : BOOLEAN]
  123.   Test 2 or more items for equality.  
  124.   You can only compare like types - eg (== "123" 123) is illegal.
  125.   eg (== foo 1), (== "one" "two"), (== (+ foo 3) bar 5).
  126. (!= value value)                 [NUMBER NUMBER : BOOLEAN]
  127.     Same as == but nonequality.  Only 2 items.
  128. (<  value1 value2) TRUE if value1 <  value2.     [NUMBER NUMBER : BOOLEAN]
  129. (<= value1 value2) TRUE if value1 <= value2.     [NUMBER NUMBER : BOOLEAN]
  130. (>  value1 value2) TRUE if value1 >  value2.     [NUMBER NUMBER : BOOLEAN]
  131. (>= value1 value2) TRUE if value1 >= value2.     [NUMBER NUMBER : BOOLEAN]
  132. (+  values)                        [NUMBERs : NUMBER]
  133.     Add a bunch of numbers  eg (+ 1 2 3 4) => 1+2+3+4
  134. (-  values)                        [NUMBERs : NUMBER]
  135.     Subtract a bunch of numbers eg (- 1 2 3 4) => 1-2-3-4 = -8
  136. (*  values)    multiply a bunch of numbers        [NUMBERs : NUMBER]
  137. (/  values)    divide a bunch of numbers        [NUMBERs : NUMBER]
  138. (+= var values)                      [TOKEN NUMBERs : NUMBER]
  139.     Add value(s) to var and assign it back to the var.  Returns the result.
  140.     Short hand for (var (+ var values)).
  141.     eg (+= foo 1) (+= foo fud 3) 
  142. (-= var values)      Subtract value from var.      [TOKEN NUMBERs : NUMBER]
  143. (*= var values)      Multiply var by value.      [TOKEN NUMBERs : NUMBER]
  144. (/= var values)      Divide var by value.          [TOKEN NUMBERs : NUMBER]
  145.  
  146. "string"
  147.   String constant.
  148.   Special characters:
  149.     \    quote the next character.  "\\" => '\'   "\^" => '^'
  150.     ^    convert the next character to a control character (make sure that
  151.       the letter is UPPERCASE!).  eg "^A"
  152.     Note: escape == ^[.
  153. 'string'
  154.   String constant.
  155.   No special characters except '' reduces to ' ie if you need a string
  156.     like "don't", you can use 'don''t'.
  157.   This form is handy for regular expressions.
  158.  
  159. (and values)                 [BOOLEAN [BOOLEAN ...] : BOOLEAN]
  160.   Logically and a bunch of things
  161.   The first FALSE value will terminate (ie the rest of the and will
  162.     not be evaluated).
  163.   Example:
  164.     (and (previous-line) (foo)):  If previous-line returns TRUE, foo is
  165.       called and that will be the result of the and.  If previous-line
  166.       returns FALSE, the and returns FALSE and foo is not called.
  167.   See also: or.                                  
  168. (arg n)                              [NUMBER : any class]
  169.   Get the nth argument from the parameter list.
  170.   The arguments are numbered 0,1...,(nargs)-1
  171.   eg (fcn 1 "two" (three)) has 3 arguments:  numeric 1, string "two" and
  172.     whatever fcn three returns.  (arg 0) returns 1, (arg 1) returns
  173.     "two", (arg 2) returns result of (three).  (arg 3), (arg -1), etc
  174.     error.
  175.   Notes:
  176.     You cannot set a arg unless it is a pointer.
  177.     See defun for how you can name the args.
  178.   See also: ask, defun, nargs.
  179. (array type name dimensions)   [TOKEN TOKEN NUMBERs [TOKEN NUMBERs] : zip]
  180.   Create an array.  Types allowed: bool, int, small-int.
  181.   (array int x 5 z 7) creates two arrays:  x with 5 ints and z with 7.
  182.   (array int y 2 3) creates an array with 2 rows of 3 ints each.
  183.   (x 3 123) sets the third element of x to 123.
  184.   (x 3) returns 123.
  185. (ask prompt(s))                       [any class(s) ... : STRING]
  186.   Get the next argument from the argument list; if the argument list is
  187.     empty, query the user.  Away